home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / CrtMathFnc.3 < prev    next >
Encoding:
Text File  |  1995-02-21  |  3.5 KB  |  104 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) CrtMathFnc.3 1.3 95/02/21 13:53:07
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_CreateMathFunc tclc 7.0
  12. .BS
  13. .SH NAME
  14. Tcl_CreateMathFunc \- Define a new math function for expressions
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
  20. .SH ARGUMENTS
  21. .AS Tcl_ValueType clientData
  22. .AP Tcl_Interp *interp in
  23. Interpreter in which new function will be defined.
  24. .AP char *name in
  25. Name for new function.
  26. .AP int numArgs in
  27. Number of arguments to new function;  also gives size of \fIargTypes\fR array.
  28. .AP Tcl_ValueType *argTypes in
  29. Points to an array giving the permissible types for each argument to
  30. function.
  31. .AP Tcl_MathProc *proc in
  32. Procedure that implements the function.
  33. .AP ClientData clientData in
  34. Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
  35. .BE
  36.  
  37. .SH DESCRIPTION
  38. .PP
  39. Tcl allows a number of mathematical functions to be used in
  40. expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
  41. \fBTcl_CreateMathFunc\fR allows applications to add additional functions
  42. to those already provided by Tcl or to replace existing functions.
  43. \fIName\fR is the name of the function as it will appear in expressions.
  44. If \fIname\fR doesn't already exist as a function then a new function
  45. is created.  If it does exist, then the existing function is replaced.
  46. \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
  47. Each entry in the \fIargTypes\fR array must be either TCL_INT, TCL_DOUBLE,
  48. or TCL_EITHER to indicate whether the corresponding argument must be an
  49. integer, a double-precision floating value, or either, respectively.
  50. .PP
  51. Whenever the function is invoked in an expression Tcl will invoke
  52. \fIproc\fR.  \fIProc\fR should have arguments and result that match
  53. the type \fBTcl_MathProc\fR:
  54. .nf
  55. .RS
  56. typedef int Tcl_MathProc(
  57. .RS
  58. ClientData \fIclientData\fR,
  59. Tcl_Interp *\fIinterp\fR,
  60. Tcl_Value *\fIargs\fR,
  61. Tcl_Value *resultPtr\fR);
  62. .RE
  63. .RE
  64. .fi
  65. .PP
  66. When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
  67. arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
  68. \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
  69. which describe the actual arguments to the function:
  70. .nf
  71. .RS
  72. typedef struct Tcl_Value {
  73. .RS
  74. Tcl_ValueType \fItype\fR;
  75. .VS
  76. .VE
  77. long \fIintValue\fR;
  78. double \fIdoubleValue\fR;
  79. .RE
  80. } Tcl_Value;
  81. .RE
  82. .fi
  83. .PP
  84. The \fItype\fR field indicates the type of the argument and is
  85. either TCL_INT or TCL_DOUBLE.
  86. It will match the \fIargTypes\fR value specified for the function unless
  87. the \fIargTypes\fR value was TCL_EITHER. Tcl converts
  88. the argument supplied in the expression to the type requested in
  89. \fIargTypes\fR, if that is necessary.
  90. Depending on the value of the \fItype\fR field, the \fIintValue\fR
  91. or \fIdoubleValue\fR field will contain the actual value of the argument.
  92. .PP
  93. \fIProc\fR should compute its result and store it either as an integer
  94. in \fIresultPtr->intValue\fR or as a floating value in
  95. \fIresultPtr->doubleValue\fR.
  96. It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE
  97. to indicate which value was set.
  98. Under normal circumstances \fIproc\fR should return TCL_OK.
  99. If an error occurs while executing the function, \fIproc\fR should
  100. return TCL_ERROR and leave an error message in \fIinterp->result\fR.
  101.  
  102. .SH KEYWORDS
  103. expression, mathematical function
  104.